PD Collection CD 1/PD Collection CD 1.iso/sound/coco/!Coconizer/ReadMe

Text File | 1994-09-24 | 27KB | 554 lines

                    ====================================
                    ==   THE COCONIZER SOUNDTRACKER   ==
                    ====================================

Coconizer consists of two aplications:
 - The soundtrack editor  !Coconizer
 - The player & toolbox   !CocoPlayr

To understand Coconizer in every detail please read the textfiles of
!CocoPlayr, too. Copyright notices can be found at the end of the text
files.


The overscan mode of Coconizer:
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
We're using a full screen mode (ie with no borders) in order to bring more
informations on screen. As everything, this has some advantages and brings
some problems. Coconizer II will run optionally in the Wimp and hence only
use a default RISC OS mode.


========================
=  SOME GENERAL NOTES  =
========================

Well, here are some basic ideas when writing a new song:

 - First of all, the song needs a title. You can type in your name (which
   can be up to 19 characters long), and use the song's filename as title.
   After that you can choose the song format, which can be either four or
   eight channels. Let's explain what this means exactly:

   The eight channel format uses the eight independent stereo voices of the
   Archimedes, which obviously sound alot better than four channels (what a
   surprise - we're not using an Amiga now!). However, as a result the
   player needs to use up more processor speed to look after the required
   DMA sound buffers. Well, whilst using Coconizer you needn't care, but if
   you're going to need a song for a fast program, you will just have to
   test it to see which is the better format. Despite all this, your Archie
   is very fast, and it's well possible to play an eight voice song, AND
   also run a program.
   On the other side there is the four channel format, which only uses four
   voices together, needing less processor time. However, on ARM3 the speed
   difference is quite small: about 7% (with 12 MHz RAMs).

 - Well, let's begin. You can now define some instruments to use in your
   composition (for an explanation of what an instrument actually is, see
   the paragraph headed "Samples"). They are labelled from "a" to "z",
   resulting in a total instrument pool of 26 samples at once (although
   future versions of Coconizer may allow the use of more samples at once).
   It is not possible to create a pattern without at least one instrument
   loaded in.

 - After you've done all this you can start editing the song itself. Full
   instructions for using Coconizer are in the next section.

   So, what is a song?
   A song consists of several patterns, each of which is 64 lines deep and
   four or eight rows wide, depending on the selected channel format.
   Patterns are used to allow you to repeat several parts in your song, to
   keep and/or beat the time, and to keep a good overview of the whole song.
   The patterns hold the information about the tones and how to play them.

 Let's see an example of how a tone information word (32 bits) is build up:

       C#1 a F 05
       / | |  \ \\_ Info Byte (left and right nibble)
      /  | |   \
     /   | |    \Command (or Effect)
    /    | |
   Note  | Instrument number
         |
    Octave number


   And the interpretation of this information is very easy:

   » "C" is the international C - in this case, the "1" holds the octave
     number, here octave 1. Currently octaves are in the range from -3 to
     +4, and this means some extremely low or high notes are possible,
     especially useful for sound effects. Furthermore the note is played as
     "C Sharp". The "#" character always indicates the sharp of a note. If
     the note entry contains nothing, than no new note is played.
   » The "a" entry says that instrument "a" (which is the first one) is used
     to play the note. By selecting an instrument its volume is set to its
     default value.
     If the instrument byte contains nothing, then the last selected one is
     used, at the same volume.
   » The next entry "F" holds the desired command or effect. In this case
     the command is "Set Speed" (see below for a list of all the commands).
   » Finally, the last entry "05" is the Infobyte, which contains values
     for the selected command/effect. In this case it means Set Speed to 5.

   Difficult? Oh no. All of this information is displayed in an expanded
   form in the head line of the edit window.


Fine, now let's continue with the main steps...

 - After creating some patterns, you should choose the sequence of them, ie
   set the order the patterns are played in.

 - Furthermore you could change the default setting of your selected
   instruments. Each of them has its own default Volume, Repeat_At and
   Repeat_Length.
   The default volume is used for playing the intrument when it is selected
   by the letter "a" - "z". The command "C = Set volume" will overwrite this
   (of course).
   If Repeat_At is zero, then the instrument will be silent after arriving
   at the samples' end. This means that the tone sounds only as long as the
   sample played. If it is set, then the instrument will start as normal but
   be repeated at this offset number, whilst playing <Repeat_Length> bytes
   each time.

 - And last but not least we come to the stereo positions of the channels.
   When a song is started, they are set in a quite logical way: it begins
   with channel one at the furthest left stereo position, and ends with
   channel eight at the furthest right position. In four channel mode the
   two furthest stereo positions on the left and right are not set.
   For finer control, there's also a command available which allows the
   setting of all the stereo positions whilst playing.


======================================
=  COCONIZER'S COMMANDS AND EFFECTS  =
======================================

Although programmed in the same way, we should distinguish carefully between
a command and an effect. A command is only performed once, like Set Speed,
or Set Volume, together with new playing instructions, ie notes. An effect,
like Arpeggio or Sliding, is performed at every interrupt call. That is,
it's not performed when set, but at the following five (or more, depending
on speed) interrupt calls, which are made until the next new note is played.
Of course, you can perform these commands/effects without playing a new
tone.

The sound playing routine is interrupt driven and is called 50 times a
second (50 Hz). At each interrupt, effects and commands can be performed.
Because 50 notes per second would be too fast for a tune, there's a counter
which counts the interrupts before a new note is played. In the following
context "each first interrupt" means the interrupt at the point when the
counter is reset.


The following effects/commands are currently available (indeed, they could
be expanded to a theoretical number of &FF) :

 * EFFECT &00 :
   Use arpeggio playing. That is, swap the note value 5 times whilst
   playing, which is the default. Or more exactly: swap it <speed-1> times.
   During these <speed-1> steps the following is performed:
   1) Add left nibble of infobyte to the note value (and play).
   2) Add right nibble to the original note (and play this).
   3) Play original (base) note.
   4) Repeat step 1, ie add left nibble, etc.
   5) Repeat step 2, ie add right nibble, etc.

   For example:
   The infobyte contains &54, and the arpeggio effect has been set. The tone
   which must be played is entered as "D". First, "D" is played. Then, in
   the first effect step, nibble &5 is added to the original note, resulting
   in the tone "G" (D - D sharp - E - F - F sharp - G). This is played. At
   the second step, nibble &4 is added to the original, resulting in the
   tone "F Sharp". This is played, and so on.

   This was originally invented on Amiga which has four channels, in order
   to make the voices sound a bit "fuller", and for other effects.

 * EFFECT &01 :
   Slide up tone, ie add infobyte*64 to the output frequency. This is
   usually done 5 times (depending on speed) while playing a note, until a
   certain frequency is achieved. This limit comes from the Amiga.

 * EFFECT &02 :
   Slide down tone, ie subtract infobyte*64 from frequency, <speed-1> times
   per "play", until a certain frequency (the Amiga limit) is achieved.

 * EFFECT &03 :
   Slide up volume. Every first interrupt, the infobyte is added to the
   current volume of the current instrument. Because of the LSB (lower sign
   bit) format of the sample system, only even infobytes are allowed, to
   achieve smooth sliding.

 * EFFECT &04 :
   Slide down volume. Subtract infobyte every first interrupt, for allowing
   slow sliding.

 * EFFECT &05 :
   Fine slide pitch up. Add infobyte*16 to frequency. There is no maximum.
   This is the preferred method of sliding the pitch.

 * EFFECT &06 :
   Fine slide pitch down. Subtract infobyte*16. The minimum is zero. This is
   the preferred pitch sliding.

 * COMMAND &07 :
   Set the stereo position of the current channel to infobyte value. Each
   used channel may have its own stereo position. The infobyte can indicate
   one of the following 7 positions:

          01 100% Left Channel
          02  83% Left Channel
          03  67% Left Channel
          04      Centre
          05  67% Right Channel
          06  83% Right Channel
          07 100% Right Channel

 * COMMAND &08 :
   Start auto volume up. That is, slide up the volume of the current
   instrument in this channel by the infobyte every first interrupt, from
   now on. This will be done automatically. In order to clear this automatic
   flag, you have to use command effect &08 with a zero infobyte.

 * COMMAND &09 :
   Start auto volume down. Opposite to &08.
   Clear this automatic flag by selecting same the command with the infobyte
   as zero.

 * COMMAND &0A :
   Start auto sliding up. That is, slide up the pitch (frequency) every
   interrupt automatically by the infobyte value.
   Clear this automatic flag by selecting same command with a zero infobyte.

 * COMMAND &0B :
   Start auto sliding down. Opposite to &0A.
   Clear this automatic flag by selecting same command with a zero infobyte.

 * COMMAND &0C :
   Set the volume of the current instrument (on current channel) to the
   infobyte value. The volume is in the range from &00 to &FF, where 0 is
   loudest and 255 totally quiet. Please note the LSB sample format (ie
   use only even numbers) and that the values have a logarithmic effect.

 * COMMAND &0D :
   Pattern break. When this command is set then the whole pattern is
   terminated, and the next one in the sequence is started. It doesn't
   matter which channel activates it.

 * COMMAND &0E :
   Position jump. The (hex!) info byte gives the sequence number where to
   jump to. Please use with caution. (NB: Tom, is the max seq nr checked?)
   Useful for several tunes in the same song which all use the same (sub-)
   set of instruments. You could have a game over tune, a title tune and so
   on, in the same song (file). When the end of one part is reached, it
   jumps with this command to its start sequence number. You'll then have
   to remember the sequence number of each part's start and use the command
   or SWI Coco_PositionJump <Number> of the player module.

 * COMMAND &0F :
   Set the play speed to value contained in the infobyte. The default speed
   is 6. That is, if the interrupt counter achieves the selected speed, then
   the next pattern information is interpreted (a new note row is played)
   and the counter is reset.

An additional note to the auto commands: Although these auto commands are
executed as commands, they actually make their appropriate effects be
started. They are included to allow you to use multiple effects at the same
time. All four auto effects may even be active at the same time (or rather:
after setting one, the next may be set too). Please don't "forget" an auto
effect once set. Clear it by setting the command together with the infobyte
as zero. Like the other effects, the auto fx are performed in the time
between two new notes, that is <speed-1> times, and only if a tone for this
channel is (still) active.


===============================================
=  TECHNICAL INFO ABOUT SAMPLES AND SAMPLING  =
===============================================

An instrument is a digitised sample file, digitised at an original base
octave (for example middle C). Current instruments must not exceed the
length of 64 KBytes. Some people digitise(d) their samples at other octaves,
so don't wonder when you hear different instruments, about their different
base octaves.
There's no clear rule which octave contains the international 'A' (or should
there be one?). Coconizer uses octave 1 for this tone. Most samples have a
frequency of 440 Hz (approx) when played as international A (A 1), but as
mentioned above, some will vary.

A sample file contains digitised data bytes. But what are they? Well, let's
see what the manual says...
 The sound DMA system of the Archimedes systematically outputs the data
 bytes at a programmed sample rate; each (16-byte) load of DMA data from
 memory is synchronized to the first stereo image position. Each byte must
 be stored as an eight bit signed logarithm, ready for direct output to the
 VIDC chip:
 Multiple channel operations are possible with two, four or eight channels.
 When output the channels are multiplexed into what is effectively one half,
 one quarter or one eight of the sample period, so the signal level per
 channel is scaled down by the same amount. Thus the signal level per
 channel is scaled, depending on the number of channels; but the overall
 signal level remains the same for all multi channel modes.

Well, why tell us this? There are some things resulting from the VIDC 8-bit
logarithmic LSB (lower sign bit) format: If you digitise or create a new
sample then the resulting file is often a (signed) linear one and therefore
not ready for direct VIDC sound output. It first has to be converted to the
correct signed logarithm format. Several nice PD tools exist which will do
this for you.

And last but not least some technical details as to the maximum and default
sample rate.
 A high sample rate will give the best sound quality. If too high a rate is
 sought then DMA request conflicts will occur, especially when high band-
 widths are also required from the Video Controller by high resolution
 screen modes. To avoid such contentions the output period must not be less
 than 4 µs. Outputting a byte to one of eight channels every 4 µs results in
 a sample period of 32 µs, which gives a maximum sample rate of 31.25 kHz
 with eight active channels. With one active channel even 250 kHz. Today CD
 players usually have about 42 kHz.
 The clock for the Sound system is derived from the system clock for the
 video controller, which is then derived by a multiple of 24. Pre RiscPC
 Archimedes' use a VIDC system clock of 24 MHz, 25.175 MHz or 36 MHz,
 depending on the screen mode and monitor type selected. The default output
 period is 6 µs, which is compatible with VIDC system clocks running at
 multiples of 4 MHz from 12 MHz upwards (ie 12 MHz, 16 MHz, 20 MHz..). The
 6 µs can't be matched with the VIDC system clock of 25.175 MHz. In this
 case the divider used is the same as for a 24 MHz VIDC system clock) which
 results in a slightly shorter output period, and so sounds are
 approximately a semitone higher.

Outputting a byte to one of eight every 6 µs results in a sample period of
48 µs, which gives a default sample rate of 20.833 kHz. Coconizer plays
either four or eight channels, so we decided to keep the default sample
rate, ie its sample period of 48 µs. The sound of the Archimedes is 8 bit
logarithmic, which is vaguely equivalent to 12 bit linear. NB: The Amiga
for example has 8 bit linear sound.


==========================
=  HOW TO USE COCONIZER  =
==========================

As a guideline for mouse handling, the left button incs/decs slowly, the
middle button steps at normal speed, and the right button steps quickly
through a list. When changing default settings like Repeat_At, then pressing
the left button together with the right one steps very quickly.
With some control icons like "Play", "Play Pattern" and "Load Inst/Song",
the left and right buttons perform different actions. The left one continues
(if possible) from the last stopped position, and the right one begins from
the start (it restarts).

You toggle channels on/off by clicking on the voice number (to the left to
the graphic equalizer). This will help you in isolating a single voice for
controlling it during editing.
When playing a song or pattern, the "DISPLAY" icon toggles the channel
display with the spectrum analyzer display. During play the cursor up/down
arrows control the overall volume (useful for external audio output).

Here's an overview of the main icons:
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
 * LOAD SONG
   Drag or double click on a song file in the usual RISC OS manner in order
   to load a new song.
   When the song has been loaded, the required instruments are loaded, so
   there will be more disk changes to be done. Coconizer always loads these
   instruments beginning with your Sample disk 01 in ascending (disk sorted)
   order. Instruments which couldn't be found in the location file are shown
   in red, and similar samples should be loaded instead (please note, they
   can't be heard when they are shown in red!).
   In case your location file is up to date, all samples will be loaded
   correctly. In case you get problems, you should locate your samples with
   !CocoPayr. Please note that !Coconizer only loads the location file when
   installing itself on the icon bar.

 * SAVE SONG
   You should always save your work with the savebox in the submenu of
   Coconizer's iconbar icon (quitting the overscan Coco mode will keep your
   song of course). This works in usual RISC OS manner.  NB: The old save
   method in the Coco overscan mode is NOT recommended because you aren't
   warned when the file already exists, and it always use the current
   selected directory (CSD) to save to, this also applies to LOAD SONG.

 * LOAD INST
   A new instrument is added to the instrument pool if the current sample
   position is empty, and an old one is replaced with the new one if its
   position was already used.
   The number to the right of the instrument in the selection list is the
   number KBytes the sample takes up on disk. The following number shows
   which disk it is located on.

 * PLAY
   Clicking the left mouse button here continues playing the song, at the
   last stopped position (if possible). The middle button continues at the
   beginning of the last stopped pattern. The right button restarts the song
   from its beginning.

 * STOP
   Used to stop playing, to leave the editing modes and to stop pattern
   playing. When clicked in edit & play_pattern (debug off) mode then the
   left button stops, and sets the cursor to the last played line. The right
   button sets the cursor to the top of the pattern.

 * EDIT PATTERN
   For editing there must be at least one instrument loaded. The current
   pattern number is then entered. You may step through your patterns by
   clicking the left/right arrow at the pattern number.
   If you wish to create a new pattern, then you must select the next blank
   pattern after the last one available, and you have to do this before you
   click on the EDIT icon.
   Quit editing with either the STOP icon or the ENTER key.

   Information about the keymap:
     The function keys F1 - F8 put the cursor into the equivalent channel.
     TAB jumps to the next channel row.
     If the cursor is at the note row of a channel, then pressing a "piano"
     key will enter the pushed note & current octave. A new instrument will
     be entered if it was not the same as the last one. Keypad keys "+" and
     "-" (or the octave icon) changes the current octave.
     Moving the cursor allows you to enter all other information, like
     commands, and so on. With Page up/down you step to the next/last green
     mark.
     RETURN steps to the upper right cursor position.
     The "~" key mutes all sound activity.

   Paste/delete functions:
     "Backspace" clears the current information entry. Key "-" clears either
     the note, inst, command or the infobyte entry, depending on the cursor
     position.
     "Insert" inserts a free tone entry at the current voice. With "Delete"
     you can kill one tone and shift the following ones up.
     The keypad "/" deletes one whole channel row and keypad "*" deletes one
     whole line. Finally, the "Home" key copies all 64 tones of your current
     channel into a buffer (with a flash to indicate this), and the "Copy"
     key writes the buffer back to the current channel.

 * PLAY PATTERN
   This command is for repeated playing of the current pattern. Clicking on
   this icon in edit mode with debug on changes its meaning: All keyboard
   presses are then recorded. The pattern is played, and your inputs are
   directly entered to the current cursor position.

 * DEBUG on (off)
   If you're in edit mode, and debug is on, then all the notes of one
   pattern line are played when moving the cursor up/down. This allows a
   very exact way of editing and/or finding "wrong" notes.
   If "play pattern" is active then recording works in slow motion, and some
   keys, like the space bar and the cursor keys, perform special actions.
   The speed of the "slow motion" may be set with function keys F9-F12, in
   interrupts: F9=3, F10=5, F11=7, F12=12.
   Note that "debug_on" disables the performance of effects, because of the
   slow motion (which means "play pattern" also mutes the effects).

 * EDIT SEQUENCE
   The selection window opens and you may choose the order of your patterns.
   With "Enter" you can input a new pattern number, or edit the current one.
   "Insert" copies the current pattern number and shifts those following
   downwards. "Delete" clears the current number and shifts the others
   upwards.
   The pattern number at the cursor position is displayed in the bottom
   window. This is the pattern "last stopped at" when considering the PLAY
   function, and will be played with the left button.

 * COMMANDS
   Well, obviously this icon lets you enter OSCLI commands. It is an old
   relique of the former non-desktop version of Coconizer and should not
   be used..

 * RESTART
   Well, clicking on this icon resets Coconizer, ie you will loose all your
   work after confirming the safety request!
   Because of the memory management of the two different channel formats,
   it's not possible to change to the other format whilst working on a song.
   Only after restarting (and losing your old song) can you select the
   desired channel format.

 * DESKTOP
   By clicking on this icon you go back to the desktop. Your work is kept
   in memory, and you can re-enter Coconizer by clicking on the iconbar.


============================
=  SOME FINAL CONCLUSIONS  =
============================

The main aim of Coconizer is to allow you to create songs and to use them
independently in your own programs, with the possibility of using either
four or eight Archimedes channels. Surely not a bad idea if you want to
create cool games and demos.

Going back to the tool 'Amiga converter' and the known converting problems:
The main aim of Coconizer is not to play Amiga songs and tunes. Although we
have tried to keep a lot of main commands and general structures, Coconizer
was created to be an Archimedes soundtracker.

The authors would also like to point out that Coconizer was the very first
soundtracker editor on the Archimedes, first release date back in July 1990,
as pure OS CLI application. Later on it has been 'moved' to the icon bar of
the Wimp. Time has shown that there are a lot of things in the editor which
could be improved or could be done different now. Still, such is life and
we'll write Coconizer II one day anyway.


======================
=  THANKS & CREDITS  =
======================

Our special thanks goes to:
 Willy Pape, Andreas Felix Föhl, Detlev Obsieger, Andreas Joos, Peter
 Straif, Ulf Zimmermann, Thomas Verbeck, Frank Kipp, Gregor Spowart and
 George Saliaris.

Yes, these are the brave men who sent support, showing us that we didn't
waste our time with Coconizer. This also made it easier for us to release
the new Wimp !CocoPlayr and its player module in the Freeware pool.

Also many thanks to Oregan Software Developments, Longman Logotron and
Cambridge International Software for their donated software.

And credits to:
· Karsten Obarski for inventing the popular SoundTracker on Amiga, and for
  a lot of Public Domain songs and instruments.
· Guttorm for his news, hints and suggestions.
· Michel for his reports and smart ideas.
· Felix for his ideas, the new command and his support.
· Andy for transforming our former text into proper English.
· The developers at Acorn for the fantastic Archimedes and its impressive
  Operating System and a special thanks to Roger Wilson for all his cool
  work inside RISC OS, especially his superb ARM BASIC plus Assembler.
· [sarcasm on] Our polytechnic school, wasting our time with dull PC stuff
  and preventing us from realeasing more on the Archimedes [sarcasm off].


===============================
=  COPYRIGHT & CONTRIBUTIONS  =
===============================

So that everybody may benefit from our efforts, we have decided to set the
status of Coconizer to Freeware. This means we keep the copyright, ie
Coconizer is our intellectual property. It's Freeware, so you may use and
copy it freely, provided all files of the apps !Coconizer and !CocoPlayr
are included unaltered, and not for any profit.

No application, except the stand alone Wimp !CocoPlayr or its player module,
is to be copied without the others included.

The software is provided 'as is'. Using it is entirely at your own risk.

Free upgrade versions of Coconizer and more soundtracks can be obtained from
us by sending some money to cover postage and an ADFS (E/F) disk. No foreign
coins please. Maybe you could try to send an international reply coupon.


          Thomas Alber            or       Eduard Pfarr
          Oggelshauser Str. 7              Atzenberger Str. 2
          88422 Bad Buchau                 88427 Otterswang
          Germany                          Germany


           Coconizer © 1990-1994 Thomas Alber & Eduard Pfarr

           Text has been revised some time ago by Andy Piper